(should be viewed with automatic line breaks on)

Game Maker 3D Terrain Editor v2
by Paul "Masterxilo" Frischknecht, Hurricane-Eye Entertainment
 2007 - 2012
visit http://www.hurricane-eye.webs.com/ and http://www.hurricane-eye.webs.com/gmterraineditor.html

== Give Feedback @ ==
Contact: http://www.hurricane-eye.webs.com/forum.html and paul_frischknecht@bluewin.ch, but I also see YouTube Video and Blog Comments, as well as private messages on the forums I'm on (e.g. Leadwerks Engine, Esenthel Engine and Game Maker Community forums).

GMC forum post:
* http://gmc.yoyogames.com/index.php?showtopic=526631

GM-D (German/Deutsch):
* http://www.gm-d.de/wbb/game-maker/game-maker-spieleentwicklung/b-hne/18938-gamemaker-terrain-editor-2-gmte-2/

Videos:
* http://www.youtube.com/watch?v=jR2jpRdaLD8
* http://www.youtube.com/watch?v=Tj_g3SdXw8Y

=== Controls ===
* Toggle fullscreen mode: F4
* Resize window : Resize window (xD, actually works!)
* Rotate camera: Arrow keys or Hold middle mouse button/Space-Key and move mouse 
* Move camera: ASWD/Move mouse to window border
* Use tool: Hold left/right mouse button
* Close: Escape/Alt+F4/Close Window (You will be asked to save the changes)
* Zoom: Mousewheel OR Ctrl+Up/Down Arrow keys OR Numpad +/-

You can drag and drop .gmte files onto the window and you can also associate and open .gmte files with GMTE 2.exe.

You can use the included "Associate GMTE files with GMTE 2 exe.bat" to associate .gmte files with this program and give them the same icon. Use "Remove GMTE file type association.reg" to remove the association ("using" means double clicking). If the bat file doesn't correctly set up the associations (e.g. because you already did manually), try running the .reg file first.

You can put custom 256x256 textures in png format into the "Textures" subfolder.

=== Loading the maps in your Game Maker games ===
Export the map you wish to use in the program as d3d (rightmost button) - the d3dexport folder is created.

A very rudimentary loading sample is included:

GMTE 2 - Loading Example.gm81

Copy this file plus the d3dexport folder to a new folder and build your project from this - or merge your existing project with this project.

=== Obj, Heightmap and texture export for other programs ===
When drawing the exported obj, make sure you draw it with texture coordinate mode set to clamp, not repeat. 
For best results (with mipmapping/linear interpolation), make sure the textures have a size that is a power of two (by making sure pixels per path * patches per model equals a power of two).

Unfortunately, the heightmap is only 8 bit so the precision is not that great. 16 bit greyscale png and raw support should be added...


=== Final Words ===
Feel free to redistribute this package UNCHANGED (the way you received it) and non-commercially! 
Always include this ReadMe (also unchanged) and do not claim you made this software (though there are certainly people who contributed a lot to this without even me knowing...). 

(This project doesn't include any "standard" open source license like "GNU-whatever", this is not needed. You know that this program shouldn't be used to keep someone alive (how should it) or anything just as good as you know that you shouldn't put a hamster in a microwave. You also know that there's no warranty or guarantee of fitness for a specific task or anything, but this program really shouldn't do any harm. E.g. the only files it deletes are the files it extracts from the maps in the mapdata folder.)

Thanks to "Yourself" (from the Gamemaker community, for the mouse 3d-2d projection maths) and the artist(s) who made the Age of Mythology ground textures (some of those are used in this program for demonstation purposes) and who made the music for Age of Empires 3 (used in the demo video for version 1) - of course also thanks the everyone else involved in the making of these games and to the creator of the Game Maker, to many people on forums and to everyone who made computers possible - this wouldn't have been possible without you!

======== THE FOLLOWING INFORMATION IS MOSTLY INTERESTING FOR DEVELOPERS ========
=== Source code "license" ===
As you can see the source code .gm81 file (for use with the Game Maker 8.1+ by Mark Overmars and YoYo Games) is included.

Feel free to use the code however you like. It would be cool if you gave credit to me ("Paul 'Masterxilo' Frischknecht") if you use it in your project, but you're not forced to. However I do want to know if you use this for something, please let me know!

In short: JUST USE IT!

=== Source code usage ===
In order to use and compile the source code, you need the following extensions:
* High-Resolution Timer Extension ( http://gmc.yoyogames.com/index.php?showtopic=279856 )
* GMUT                            ( http://dl.dropbox.com/u/8014211/WebsiteProjectUploads/GMUT.zip )
* GMZ Zip Archiver                ( http://gmc.yoyogames.com/index.php?showtopic=512333 )
* GM DragAcceptFiles              ( http://gmc.yoyogames.com/index.php?showtopic=513941 )

If I have forgotten something, let me know!

=== Project Design Conventions ===
This list outlines the design conventions followed in the source code of this project:

* All resource identifiers start with a 3 letter lowercase version of their type. E.g. snd_..., spr_..., fnt_... . However, variables, scripts and objects don't have such a prefix.
* All identifiers use camelCase to differentiate words. Only object (class) names start with uppercase letters. All identifiers follow the rules for variables (no spaces etc.).
* Global functions differentiate words with underscore and don't use camel case (like the built in functions).
* As few objects as possible are used and inheritance is used as much as possible.
* User defined events and alarms are not used. Script identifiers/indexes are passed instead to create virtual methods.
* Global varibles as well as constants are written all uppercase. Global variables should be used rarely and changed even less.
* (Purely) private variables and scrips start with underscore.
* There's a space after, but not before commas.
* There are no brackets used with "return".
* All method scripts start with the classname followed by an underscore.
* Methods of other objects are called like: "with (<instance>) Class_methodName();".
* Encapsulation is encouraged, but public variables are ok to be used.
* Double quotation marks are used for strings, single ones for characters.
* All 3D Objects have a depth > 0, all 2D objects a depth < 0. Only the controller has 0 depth. There are constants for the depth levels. -- On creation, all objects start with depth 0 except the controller to ensure that its Create event is called first.
* All drawing settings must be reset by the setter. This does not apply to settings different between 2D and 3D mode that are changed while drawing outside of the draw event of the objects. 
* Global room setup code may not be used. Per instance setup code is ok to be used.

=== Known Bugs and Problems ===
* Sometimes when the application loses focus the textures get missing and the lighting (normals) gets messed up.
* When you hold space (to turn the camera) while editing, the editing is not done until you release the spacekey, and it's messed up...
* The first time the window is maximized, it's only made the size of the screen, not truly maximized?
* Windows can only be maximized on primary monitor.
* Framerate drops dramatically if the window is partially covered by the Windows Vista/7 start orb. (This is more of a windows problem as this happens with any application)
* Sometimes a blue rectangle appears where the first terrain model/patch is.
* Crashes after a windows 7/vista UAC warning ("secure desktop") is diaplayed or the display/graphics card is reset for some other reason (e.g. because of a video mode change).
* The window is not affected by Windwows 7's "move windows to left/right half" and "fit to screen height" window modifications (however, maximizing works).
* When loading a new terrain/resizing, the camera position stays the same and the position clamps only after you move.

=== TODO, Planned features ===
* Generate Shortcut info text from actual shortcut.
* Add option to open last opened file.
* Don't update if out of focus/mouse too far out of screen?
* Add FP view... (Flying camera) and ground walking.
* non-power two textures working with all features? ... Use ONLY power of two textures (mipmapping in other engines)
* Add more shortcut keys...
* Redesign UI...
* Allow per point height manipulation
* Remove mousewheel/mmb camera control (?)
* More exporting methods: low quality exporting (with colormap as texture) ?...
* Add heightmap & texturemap importing, colormap importing
* Add colorblending tool (to slightly alter the textures color). Allow to select blend mode...
* Allow to quickly export the whole texture and/or heightmap to the clipboard, edit in an external program and import again from the clipboard.
* Implement random terrain generating (scripting?)
* Reset camera position when loading new map
* (Remember last used texture and brush settings? Remember per map? Have the option? Reset button?)
* Default window position should be centered.
* Implement undo/redo functionality!
* Allow dragging the map out of the window to a folder, creating the map file there (working on plugin/extension...)
* Make camera move faster while holding shift.
* Optimize... Speed up loading, saving.
* Show loading/saving progress! (Progress bar extension...)
* Add ability to change working/texturesearch/settings directory...
* Make brush sculpting intensity derive from a brush texture.
* Display brush texture instead of outline.
* Add custom brushes. Adjustable round and square brush will be built in (or scripted?). [ROUND done, but not for sculpting]

* Add saving/loading/creating feedback (write progress bar extension?).
* Add multitouch & touchpen support (exnsion WIP...).
* Use cleanmem: http://gmc.yoyogames.com/index.php?showtopic=438215 (?)
* Implement more tools (ramp...).
* Try to make program fail completely as rarely as possible (e.g. when loading if the heightmap is missing but the rest is there, try to reconstruct width and height and load anyways. Same with saving... PARTIALLY DONE).
* Add a way to change pixels per patch (texture scaling) and patches per section (texture and model recreation) values.
* Does not save to current filename after "failed to load textures"...?
* Add way to see all map attributes/mapinfo.
* Preserve external mapattributes./Preserve attributes not created by this editor in map files.
* Add program info/"About" window.
* Add ability to change pixels per patch for every section (what to do on resizing?). Stretch loaded textures...
* Add tooltip for current terrain tool if not on interface.
* Add map combine & crop function. --> selection/copy paste mode...
* Show mouse coordinate (?).
* Don't save unchanged textures (keep currently loaded map in mapdata folder).
* Add mipmapping (views/znear, zfar)
* Make camera adjust to height. Make sure raycasts still work...
* Write importing library for people to use in their own game.
* Export useful functions to extension.
* Add other texturing engines: per vertex (smaller files & less memory), per vertex/patch blending textures ( la WC3, aom --> only smaller files, same memory impact)
* Add double/multi painting (two textures at once). (brush stack?)
* Add ability to scale the painted texture...
* Add keyboard controls for all tools (also brush settings...)
* Add simple object placement.
* Add language switching. (while running or only after restart?)
* Add free flight camera.
* Extend height to outside of terrain. (?)
* Control viewrange differently: Add horizontal slider...
* Reload externally changed files. (including settings) (-> extension...)
* Reset lighting and texture on new map? Use secondary texture?
* Make faltten tools create smoother outer boundaries
* Repair messed up gui system (obj foreground drawer has errors if obj COntroller is not the last object created...).

* Allow shifting whole map by x amount of patches.
* Handle resizing like mspaint (point on lower right corner you can drag).
* Support textures of arbitrary size (already supported? What happens?) and more formats(?).
* Use fewer scripts, events, objects (hirarchy), instances (combine functionality).
* Object creation event not executed after first step...?
* Prerender more...

=== GMTE File Format Specification ===
GMTE files (extension .gmte) are simple standard .zip files with renamed extension. You can open them with any unzipping program (e.g. 7-Zip, WinZip, WinRar).
They contain a folder called "mapdata" inside which you'll find the ground textures in .png format, called "x.y.png" where x and y are the coordinates of the terrain block/model using this texture.

Other than these textures, there are some attribute files containing plain text data. These files contain the other terrain data.

The "heightGrid" attribute file is created from the terrain height grid ds_grid structure using ds_grid_write and read using ds_grid_read.

=== Other implementation information ===
* The Settings are stored one per file in the Settings subfolder. These are plain text files without extension. If you use this application on multiple computers and have it in a folder synchronized with Dropbox, it is recommended to not sync the Settings folder as especially the LASTPATH setting is path-specific.
* The "Associate GMTE files with GMTE 2 exe.bat" creates a temporary registry file (.reg) which is then run. This cannot be a static file as we need to know the exact path of the GMTE 2.exe. Do not rename the exe!
